---
description: Steps required to deploy SaaS Boilerplate on AWS
---

# Step 1: Configure AWS credentials

import useBaseUrl from '@docusaurus/useBaseUrl';
import ProjectName from '../../shared/components/ProjectName.component';
import FreshAWSAccountInfo from '../../shared/partials/_freash-aws-account-info.mdx';

## Prerequisites

- An **AWS account** with an admin role

:::tip
You can skip this step if you prefer to manage AWS credentials without using AWS Vault, but it is recommended to
follow this guide for improved security.
:::

<FreshAWSAccountInfo />

## Store AWS credentials in secure place

Keeping your AWS credentials in plain text in `~/.aws/config/` or `~/.aws/credentials` is not very secure.
We recommend using [aws-vault](https://github.com/99designs/aws-vault) – "A vault for securely storing and accessing
AWS credentials in development environments".

AWS Vault is a command-line tool that securely manages AWS access credentials using an encrypted local file on your
computer. It allows you to manage multiple AWS accounts and roles, switch between them without entering credentials
repeatedly, and rotate access keys for improved security. It also integrates with other AWS command-line tools
and supports MFA for added protection.

Visit official [aws-vault](https://github.com/99designs/aws-vault) documentation for installation instructions.

### Create base profile

First you need to create a profile for your AWS credentials. Just using this is a great security improvement because
you no longer store them in plain text.

```shell
aws-vault add my-profile
```

From now on you can just set environmental variable `AWS_PROFILE=my-profile` and all AWS commands should be able to pick
up your credentials automatically.

:::info

You should find your `Enter Access Key Id` and `Enter Secret Key` in <br /> the `My security credentials` section of
your AWS web panel.

:::

### Create profile for your project

You will use this profile to execute any CLI commands that interact with AWS: AWS CLI, Serverless, REST API, etc.

Generally, it is considered a best practice to use temporary security credentials when working on an assumed IAM role,
rather than relying on your permanent ones. To achieve this, you will need to create a new IAM role with the appropriate
permissions. In this guide, we will create a full-access admin role for demonstration purposes.

#### Create IAM Role

Create the new IAM role with following permissions and give it a name, for example `SaaSBoilerplateAdminRole`:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": "*"
        }
    ]
}
```

You also need to edit the trust policy, available in "Trust relationships" tab in the AWS web panel.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:root"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

- `<AWS_ACCOUNT_ID>` is the ID of your AWS account that you want to use for deployment. It is a 12-digit number you can
get from the account settings page.

You will need the `arn` of the IAM role you just created in the next step. It is visible on the role's details page in aws
web panel.

#### Modify configuration file

Next, create a new entry in `~/.aws/config` file:
- set the name of the profile,
- set `source_profile` to the name of the base profile you created few steps before,
- set `role_arn` to the `arn` of the IAM role you created in previous step,
- set `region` to the AWS region you'd like to use for deployment of <ProjectName/>.

```shell title="~/.aws/config"
[profile my-profile]
region=eu-west-1

// highlight-start
[profile saas]
source_profile = my-profile
role_arn = arn:aws:iam::<AWS_ACCOUNT_ID>:role/SaaSBoilerplateAdminRole
region=eu-west-1
// highlight-end
```

#### Update `.env` file

Now you can use that profile name in `.env` file in root of your project

```dotenv title=".env"
PROJECT_NAME=saas
AWS_VAULT_PROFILE=saas
...
```

### AWS vault usage

From now on you can use aws-vault for secure connection with AWS platform.
Always make sure you are in a proper aws-vault context when you run commands that use AWS CLI.

We created a CLI command that will automatically use `aws-vault` if it is detected in your system:

```shell
pnpm saas aws set-env [STAGE_NAME]
```

After this you'll have proper AWS credentials available in environmental variables and any command will be run against
a specific environment stage (`qa` in the example above).

:::info

Check out the [usage docs](https://github.com/99designs/aws-vault/blob/master/USAGE.md) for more info about how you can
utilize aws-vault.

:::


### _[optional]_ Multi-factor authentication

You _may_ be also be required to configure MFA for your AWS user and AWS Vault profile.

If during the deployment you encounter similar error:

```
…
3:25:45 PM | UPDATE_FAILED        | AWS::CodeBuild::Project     | PipelineConfigWebA...ildProject04B4719B
AccessDenied. User doesn't have permission to call iam:GetRole
```

consider configuring MFA, as documented in [the official docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-root).

Copy the serial MFA device serial number

<img
  src={useBaseUrl('img/initial-setup-mfa-serial-number.png')}
  alt="MFA serial number"
/>

And paste it into the `~/.aws/config` as `mfa_serial` property (example below) and save the file.

```shell {4}
[profile saas]
source_profile = your-personal-user-name
role_arn = arn:aws:iam::123456789:role/SaaSBoilerplateAdminRole
mfa_serial=arn:aws:iam::123456789:mfa/someone@example.com
```

:::note
Unfortunately, from now on, you will have to enter MFA every time you log into the AWS console or run `aws-vault`
:::

